.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at
.\" https://opensource.org/licenses/CDDL-1.0
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright 2020 Richard Elling
.\" .Dd June 14, 2020
.TH zpool_influxdb 8
.SH NAME
zpool_influxdb \- collect zpool statistics in influxdb line protocol format
.SH SYNOPSIS
.LP
.nf
\fBzpool_influxdb\fR [--execd] [--no-histogram] [--sum-histogram-buckets]
[--tags key=value] [pool]
\fBzpool_influxdb\fR --help
.fi
.SH DESCRIPTION
The \fBzpool_influxdb\fR command produces influxdb line protocol compatible
metrics from zpools. Like the \fBzpool\fR command, \fBzpool_influxdb\fR
reads the current pool status and statistics. Unlike the \fBzpool\fR
command which is intended for humans, \fBzpool_influxdb\fR formats the
output in influxdb line protocol. The expected use is as a plugin to a
metrics collector or aggregator, such as telegraf.

By default, \fBzpool_influxdb\fR prints pool metrics and status in the
influxdb line protocol format. All pools are printed, similar to
the \fBzpool status\fR command. Providing a pool name restricts the
output to the named pool.

Like the \fBzpool\fR command, \fBzpool_influxdb\fR uses internal data
structures that can change over time as new ZFS releases are made.
Therefore, the \fBzpool_influxdb\fR command must be compiled against the
ZFS source. It is expected that later releases of ZFS includes compatible
\fBzpool_influxdb\fR and \fBzpool\fR commands.

.SH OPTIONS
.TP
\fB\--execd\fR, \fB-e\fR
Run in daemon mode compatible with telegraf`s \fBexecd\fR plugin.
In this mode, the pools are sampled every time there is a [return] on stdin.
Once a sample printed, \fBzpool_influxdb\fR waits for another [return].
When run on a terminal, use [ctrl+C] to exit.
.TP
\fB\--no-histogram\fR, \fB-n\fR
Do not print latency and I/O size histograms. This can reduce the total
amount of data, but one should consider the value brought by the insights
that latency and I/O size distributions provide. The resulting values
are suitable for graphing with grafana's heatmap plugin.
.TP
\fB--sum-histogram-buckets\fR, \fB-s\fR
Accumulates bucket values. By default, the values are not accumulated and
the raw data appears as shown by \fBzpool iostat\fR. This works well for
grafana's heatmap plugin. Summing the buckets produces output similar to
prometheus histograms.
.TP
\fB--tags\fR, \fB-t\fR
Adds specified tags to the tag set. Tags are key=value pairs and multiple
tags are separated by commas. No sanity checking is performed.
See the InfluxDB Line Protocol format documentation for details on escaping
special characters used in tags.
.TP
\fB\--help\fR, \fB\-h\fR
Print a usage summary.

.SH SEE ALSO
.LP
\fBzpool-status\fR(8)
\fBzpool-iostat\fR(8)
.PP
Influxdb https://github.com/influxdata/influxdb
.PP
Telegraf https://github.com/influxdata/telegraf
.PP
Grafana https://grafana.com
.PP
Prometheus https://prometheus.io
